.\" ****************************************************************************
.\"  recorder_trace_set.3                                      recorder library
.\" ****************************************************************************
.\"
.\"   File Description:
.\"
.\"     Man page for the recorder library
.\"
.\"     This documents recorder_trace_set(3) and RECORDER_TRACE
.\"
.\"
.\"
.\"
.\"
.\"
.\" ****************************************************************************
.\"  (C) 2019 Christophe de Dinechin <christophe@dinechin.org>
.\" %%%LICENSE_START(LGPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU Lesser General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU Lesser General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU Lesser General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.\" ****************************************************************************

.TH recorder_trace_set 3  "2019-03-09" "1.0" "Recorder Library"

.\" ----------------------------------------------------------------------------
.SH NAME
.\" ----------------------------------------------------------------------------
recorder_trace_set \- Configure tracing for event recorders
.br
RECORDER_TRACE \- Retrieve configured value


.\" ----------------------------------------------------------------------------
.SH SYNOPSIS
.\" ----------------------------------------------------------------------------
.nf
.B #include <recorder/recorder.h>
.PP
.BI "int recorder_trace_set(const char * " trace_set ");"
.BI "#define RECORDER_TRACE(" trace_name ") ..."
.fi
.PP


.\" ----------------------------------------------------------------------------
.SH DESCRIPTION
.\" ----------------------------------------------------------------------------
.PP
The
.BR recorder_trace_set()
function configures tracing for event recorder, based on a trace
description given in
.I trace_set.
The function accepts a NULL input. A typical usage is to call it twice
at the beginning of the program, the first time to set some default
configuration for important recorders such as warnings or errors, the
second time to pass some environment variable letting users configure
tracing easily.

.PP
.EX
    /* Activate tracing for all _warning and _error event recorders */
    recorder_trace_set(".*_(warning|error)");

    /* User trace configuration, possible overriding the above */
    recorder_trace_set(getenv("MY_PROGRAM_TRACES"));
.EE

.PP
The trace description is a space-delimited list of trace
actions. Alternatively, a colon
.B (:)
can also be used as a separator.

.PP
Each trace action starts with a regular expression used to select
event recorders by name. That regular expression can optionally be
followed by an equal sign
.B =
itself followed by either a numerical value or a comma-separated list
of names.

.SS Tracing
.PP
If a numerical value is given, this value is associated to the
selected recorder(s), and can be read in the program by using
.BI "RECORDER_TRACE(" trace_name ")."

.PP
The configured value is primarily used to activate tracing for the
.BR record(3)
and
.BR record_fast(3)
functions. When the value is non-zero, these functions will
immediately show the events (tracing mode). Otherwise, they will
simply record the events.

.PP
If no equal sign is given, the numerical value 1 is used.

.SS Sharing for real-time graphing
.PP
If a comma-separated list of names is given, the corresponding
event recorder is
.I shared
for use by external programs such as
.BR recorder_scope(1).
All events must have the same number and type of arguments. The
comma-separated list sets the names of the data channels that can then
be graphed in real-time.

.SS Special trace selectors
.PP
A number of trace selectors have a special meaning, and are normally
intended for the user of the program.

.TP
.B help
displays the list of all available recorders, along with the
associated self-documentation string.

.TP
.B share
sets the name of the shared-memory file used to communicate with
external programs, see
.BR recorder_share (3).

.TP
.B dump
causes a recorder dump. See
.BR recorder_dump (3).

.TP
.B traces
lists the current values for all trace configurations.

.TP
.B all
activates all traces.


.\" ----------------------------------------------------------------------------
.SH RETURN VALUE
.\" ----------------------------------------------------------------------------
.PP
The function can return one of:

.TP
.B RECORDER_TRACE_OK
Thec trace description was successfully applied

.TP
.B RECORDER_TRACE_INVALID_NAME
One of the trace selection regular expressions is invalid.

.TP
.B RECORDER_TRACE_INVALID_VALUE
One of the trace configuration values is neither a numerical value nor a
comma-separated list of names.


.\" ----------------------------------------------------------------------------
.SH EXAMPLES
.\" ----------------------------------------------------------------------------
.PP
The program below records its input arguments, and crashes if passed
.I crash
as the first command-line argument.
.PP
.in +4n
.EX
#include <recorder/recorder.h>
#include <string.h>

RECORDER(program_args, 32, "Program command-line arguments");
int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    for (a = 0; a < argc; a++)
        record(program_args, "Argument %d is %+s", a, argv[a]);

    if (argc >= 2 && strcmp(argv[1], "crash") == 0)
    {
        char *ptr = NULL;
        strcpy(ptr, argv[1]);
    }
}
.EE
.in -4n
.PP
When a crash occurs, previously recorded events are printed out on the
console.

.PP
The program below is an instrumented version of the classical
recursive Fibonacci computation. It uses several recorders
corresponding to different types of events, and activates warnings and
errors in a way that can be configured by setting an environment variable.
.PP
.in +4n
.EX
#include <recorder/recorder.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

RECORDER(fib_main,    32, "Loops in fib function");
RECORDER(fib_loops,   32, "Loops in fib function");
RECORDER(fib_warning, 32, "Warnings in fib function");
RECORDER(fib_error,   32, "Errors in fib function");

int fib(int n)
{
    if (n <= 1) {
        if (n < 0)
            record(fib_error, "fib is undefined for negative value %d", n);
        return n;
    }
    record(fib_loops, "Computing fib(%d)", n);
    int result = fib(n-1) + fib(n-2);
    record(fib_loops, "Computed fib(%d) = %d", n, result);
    return result;
}

int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    recorder_trace_set(".*_warning=35 .*_error");
    recorder_trace_set(getenv("FIB_TRACES"));
    for (a = 1; a < argc; a++) {
        int n = atoi(argv[a]);
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computing for %d may take a while", n);
        printf("fib(%d) = %d\n", n, fib(n));
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computation for %d finally completed", n);
    }
}
.EE
.in -4n
.PP
This program will produce an output similar to the following:
.PP
.in +4n
.EX
% fib 1 2 3 4 10 20 30 35 10 40 -1
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(10) = 55
fib(20) = 6765
fib(30) = 832040
[2714667 0.177725] fib_warning: Computing for 35 may take a while
fib(35) = 9227465
[32575370 1.859156] fib_warning: Computation for 35 finally completed
fib(10) = 55
[32575547 1.859171] fib_warning: Computing for 40 may take a while
fib(40) = 102334155
[363735828 20.527882] fib_warning: Computation for 40 finally completed
[363735829 20.527887] fib_error: fib is undefined for negative value -1
fib(-1) = -1
.EE
.in -4n
The first column in trace outputs is the number of events that were
recorded. THe second column is the time in seconds since the program
started.

.PP
The same program can also be run with additional tracing or warnings,
for example:
.PP
.in +4n
.EX
% FIB_TRACES="recorder_location fib_loops fib_warning=3" /tmp/fib 3 4
/tmp/fib.c:33:[82 0.000496] fib_warning: Computing for 3 may take a while
/tmp/fib.c:18:[83 0.000561] fib_loops: Computing fib(3)
/tmp/fib.c:18:[84 0.000570] fib_loops: Computing fib(2)
/tmp/fib.c:20:[85 0.000575] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[86 0.000581] fib_loops: Computed fib(3) = 2
fib(3) = 2
/tmp/fib.c:36:[87 0.000590] fib_warning: Computation for 3 finally completed
/tmp/fib.c:33:[88 0.000596] fib_warning: Computing for 4 may take a while
/tmp/fib.c:18:[89 0.000601] fib_loops: Computing fib(4)
/tmp/fib.c:18:[90 0.000607] fib_loops: Computing fib(3)
/tmp/fib.c:18:[91 0.000612] fib_loops: Computing fib(2)
/tmp/fib.c:20:[92 0.000619] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[93 0.000625] fib_loops: Computed fib(3) = 2
/tmp/fib.c:18:[94 0.000664] fib_loops: Computing fib(2)
/tmp/fib.c:20:[95 0.000707] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[96 0.000724] fib_loops: Computed fib(4) = 3
fib(4) = 3
/tmp/fib.c:36:[97 0.000741] fib_warning: Computation for 4 finally completed
.EE
.in -4n

.\" ----------------------------------------------------------------------------
.SH BUGS
.\" ----------------------------------------------------------------------------
.PP
When a recorder is shared, incorrect data can be fetched by the client
graphing program if the types and number of arguments is not
consistent for all entries in the recorder.

.PP
Bugs should be reported using https://github.com/c3d/recorder/issues.


.\" ----------------------------------------------------------------------------
.SH SEE ALSO
.\" ----------------------------------------------------------------------------
.BR RECORDER_DEFINE (3),
.BR RECORDER_DECLARE (3)
.br
.BR recorder_dump (3),
.BR recorder_dump_for (3),
.br
.BR recorder_configure_output (3),
.BR recorder_configure_show (3)
.br
.BR recorder_configure_format (3),
.BR recorder_configure_type (3)

.PP
Additional documentation and tutorials can be found
at https://github.com/c3d/recorder.


.\" ----------------------------------------------------------------------------
.SH AUTHOR
.\" ----------------------------------------------------------------------------
Written by Christophe de Dinechin
